<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>convolve</title>
    <link rel="stylesheet" type="text/css" href="csound.css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.78.1" />
    <link rel="home" href="index.html" title="The Canonical Csound Reference Manual" />
    <link rel="up" href="OpcodesTop.html" title="Orchestra Opcodes and Operators" />
    <link rel="prev" href="convle.html" title="convle" />
    <link rel="next" href="copya2ftab.html" title="copya2ftab" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">convolve</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="convle.html">Prev</a> </td>
          <th width="60%" align="center">Orchestra Opcodes and Operators</th>
          <td width="20%" align="right"> <a accesskey="n" href="copya2ftab.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="refentry">
      <a id="convolve"></a>
      <div class="titlepage"></div>
      <a id="IndexConvolve" class="indexterm"></a>
      <div class="refnamediv">
        <h2>
          <span class="refentrytitle">convolve</span>
        </h2>
        <p>convolve — 
      Convolves a signal and an impulse response.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp95541168"></a>
        <h2>Description</h2>
        <p>
      Output is the convolution of signal <span class="emphasis"><em>ain</em></span> and the impulse response contained in <span class="emphasis"><em>ifilcod</em></span>. If more than one output signal is supplied, each will be convolved with the same impulse response. Note that it is considerably more efficient to use one instance of the operator when processing a mono input to create stereo, or quad, outputs. 
    </p>
        <p>
      Note: this opcode can also be written as <a class="link" href="convle.html" title="convle"><em class="citetitle">convle</em></a>.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp95544496"></a>
        <h2>Syntax</h2>
        <pre class="synopsis">ar1 [, ar2] [, ar3] [, ar4] <span class="command"><strong>convolve</strong></span> ain, ifilcod [, ichannel]</pre>
      </div>
      <div class="refsect1">
        <a id="idp95546512"></a>
        <h2>Initialization</h2>
        <p>
      <span class="emphasis"><em>ifilcod</em></span> -- integer or character-string denoting an impulse response data file. An integer denotes the suffix of a file <span class="emphasis"><em>convolve.m</em></span>; a character string (in double quotes) gives a filename, optionally a full pathname. If not a fullpath, the file is sought first in the current directory, then in the one given by the environment variable SADIR (if defined). The data file contains the Fourier transform of an impulse response. Memory usage depends on the size of the data file, which is read and held entirely in memory during computation, but which is shared by multiple calls.
    </p>
        <p>
      <span class="emphasis"><em>ichannel</em></span> (optional) -- which channel to use from the impulse response data file.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp95549792"></a>
        <h2>Performance</h2>
        <p>
      <span class="emphasis"><em>ain</em></span> -- input audio signal.
    </p>
        <p>
      <span class="emphasis"><em>convolve</em></span> implements Fast Convolution. The output of this operator is delayed with respect to the input. The following formulas should be used to calculate the delay:
      </p>
        <div class="informalexample">
          <pre class="programlisting">
  For (1/kr) &lt;= IRdur:
          Delay = ceil(IRdur * kr) / kr
  For (1/kr) &gt; IRdur: 
          Delay = IRdur * ceil(1/(kr*IRdur))
  Where:
          kr  = Csound control rate
          IRdur = duration, in seconds, of impulse response
          ceil(n) = smallest integer not smaller than n</pre>
        </div>
        <p>
    </p>
        <p>
      One should be careful to also take into account the initial delay, if any, of the impulse response. For example, if an impulse response is created from a recording, the soundfile may not have the initial delay included. Thus, one should either ensure that the soundfile has the correct amount of zero padding at the start, or, preferably, compensate for this delay in the orchestra (the latter method is more efficient). To compensate for the delay in the orchestra, subtract the initial delay from the result calculated using the above formula(s), when calculating the required delay to introduce into the 'dry' audio path.
    </p>
        <p>
      For typical applications, such as reverb, the delay will be in the order of 0.5 to 1.5 seconds, or even longer. This renders the current implementation unsuitable for real time applications. It could conceivably be used for real time filtering however, if the number of taps is small enough.
    </p>
        <p>
      The author intends to create a higher-level operator at some stage, that would mix the wet &amp; dry signals, using the correct amount of delay automatically.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp95556432"></a>
        <h2>Examples</h2>
        <p>
      Create frequency domain impulse response file using the <a class="link" href="cvanal.html" title="cvanal"><em class="citetitle">cvanal utility</em></a>:
      </p>
        <pre class="screen">
csound -Ucvanal l1_44.wav l1_44.cv</pre>
        <p>
    </p>
        <p>
      Determine duration of impulse response. For high accuracy, determine the number of sample frames in the impulse response soundfile, and then compute the duration with:
      </p>
        <div class="literallayout">
          <p><br />
duration = (sample frames)/(sample rate of soundfile)</p>
        </div>
        <p>
    </p>
        <p>
      This is due to the fact that the <a class="link" href="sndinfo.html" title="sndinfo"><em class="citetitle">sndinfo utility</em></a> only reports the duration to the nearest 10ms. If you have a utility that reports the duration to the required accuracy, then you can simply use the reported value directly.
      </p>
        <pre class="screen">
sndinfo l1_44.wav</pre>
        <p>

      </p>
        <div class="literallayout">
          <p><br />
length = 60822 samples, sample rate = 44100<br />
 <br />
Duration = 60822/44100 = 1.379s.</p>
        </div>
        <p>
    </p>
        <p>
      Determine initial delay, if any, of impulse response. If the impulse response has not had the initial delay removed, then you can skip this step. If it has been removed, then the only way you will know the initial delay is if the information has been provided separately. For this example, let's assume that the initial delay is 60ms (0.06s)
    </p>
        <p>
      Determine the required delay to apply to the dry signal, to align it with the convolved signal:

      </p>
        <div class="literallayout">
          <p><br />
  If kr = 441:<br />
        1/kr = 0.0023, which is &lt;= IRdur (1.379s), so:<br />
        Delay1  = ceil(IRdur * kr) / kr<br />
                = ceil(608.14) / 441<br />
                = 609/441<br />
                = 1.38s</p>
        </div>
        <p>
        
      </p>
        <div class="literallayout">
          <p><br />
  Accounting for the initial delay:<br />
        Delay2  = 0.06s<br />
   Total delay  = delay1 - delay2<br />
                = 1.38 - 0.06<br />
                = 1.32s</p>
        </div>
        <p>
    </p>
        <p>
      Here is similar example of the convolve opcode. It uses the file <a class="ulink" href="examples/convolve.csd" target="_top"><em class="citetitle">convolve.csd</em></a>.

      </p>
        <div class="example">
          <a id="idp95567760"></a>
          <p class="title">
            <strong>Example 134. Example of the convolve opcode.</strong>
          </p>
          <div class="example-contents">
            <p>See the sections <a class="link" href="UsingRealTime.html" title="Real-Time Audio"><em class="citetitle">Real-time Audio</em></a> and <a class="link" href="CommandFlags.html" title="Csound command line"><em class="citetitle">Command Line Flags</em></a> for more information on using command line flags.</p>
            <pre class="programlisting">
<span class="csdtag">&lt;CsoundSynthesizer&gt;</span>
<span class="csdtag">&lt;CsOptions&gt;</span>
<span class="comment">; Select audio/midi flags here according to platform</span>
<span class="comment">;-odac     ;;;RT audio out</span>
-iadc    <span class="comment">;;;uncomment -iadc if RT audio input is needed too</span>
<span class="comment">; For Non-realtime ouput leave only the line below:</span>
<span class="comment">;-o convolve.wav -W ;;; for file output any platform</span>
<span class="csdtag">&lt;/CsOptions&gt;</span>
<span class="csdtag">&lt;CsInstruments&gt;</span>
<span class="comment">; NB: 'Small' reverbs often require a much higher</span>
<span class="comment">; percentage of wet signal to sound interesting. 'Large'</span>
<span class="comment">; reverbs seem require less. Experiment! The wet/dry mix is</span>
<span class="comment">; very important - a small change can make a large difference.</span>

<span class="ohdr">sr</span> <span class="op">=</span> 44100
<span class="ohdr">ksmps</span> <span class="op">=</span> 32
<span class="ohdr">nchnls</span> <span class="op">=</span> 2
<span class="ohdr">0dbfs</span> <span class="op">=</span> 1
<span class="comment">;The analysis file is not system independent! </span>
<span class="comment">; create "rv_mono.wav" and "rv_stereo.wav" with cvanal first!</span>

<span class="oblock">instr</span> 1 

imix <span class="op">=</span> 0.25	<span class="comment">;wet/dry mix. Vary as desired.</span>
ivol <span class="op">=</span> 1 	<span class="comment">;Overall volume level of reverb. May need to adjust</span>
<span class="comment">;when wet/dry mix is changed, to avoid clipping.</span>

idel   <span class="opc">filelen</span> p4			<span class="comment">;calculate length and number of channels of soundfile</span>
<span class="opc">print</span>  idel
ichnls <span class="opc">filenchnls</span>  p4
<span class="opc">print</span>  ichnls

<span class="octrl">if</span> (ichnls <span class="op">==</span> 1) then

adry    <span class="opc">soundin</span> "fox.wav"               <span class="comment">; input (dry) audio</span>
awet    <span class="opc">convolve</span> adry,"rv_mono.cva"	<span class="comment">; mono convolved (wet) audio</span>
awet    <span class="opc">diff</span>    awet                    <span class="comment">; brighten</span>
adrydel <span class="opc">delay</span>   (1<span class="op">-</span>imix)<span class="op">*</span>adry, idel	<span class="comment">; Delay dry signal to align it with convolved signal</span>
					<span class="comment">; Apply level adjustment here too.</span>
<span class="opc">outs</span>    ivol<span class="op">*</span>(adrydel<span class="op">+</span>imix<span class="op">*</span>awet),ivol<span class="op">*</span>(adrydel<span class="op">+</span>imix<span class="op">*</span>awet) <span class="comment">; Mix wet &amp; dry</span>

<span class="octrl">else</span>

adry    <span class="opc">soundin</span> "fox.wav"               <span class="comment">; input (dry) audio</span>
awet1, awet2 <span class="opc">convolve</span> adry,"rv_stereo.cva" <span class="comment">; stereo convolved (wet) audio</span>
awet1   <span class="opc">diff</span>    awet1                   <span class="comment">; brighten left</span>
awet2   <span class="opc">diff</span>    awet2                   <span class="comment">; and brighten right</span>
adrydel <span class="opc">delay</span>   (1<span class="op">-</span>imix)<span class="op">*</span>adry, idel     <span class="comment">; Delay dry signal to align it with convolved signal</span>
					<span class="comment">; Apply level adjustment here too.</span>
<span class="opc">outs</span>    ivol<span class="op">*</span>(adrydel<span class="op">+</span>imix<span class="op">*</span>awet1),ivol<span class="op">*</span>(adrydel<span class="op">+</span>imix<span class="op">*</span>awet2) <span class="comment">; Mix wet &amp; dry signals</span>

<span class="octrl">endif</span>

<span class="oblock">endin</span>

<span class="csdtag">&lt;/CsInstruments&gt;</span>
<span class="csdtag">&lt;CsScore&gt;</span>

<span class="stamnt">i</span> 1 0 4 "rv_mono.wav"
<span class="stamnt">i</span> 1 5 4 "rv_stereo.wav"

<span class="stamnt">e</span>
<span class="csdtag">&lt;/CsScore&gt;</span>
<span class="csdtag">&lt;/CsoundSynthesizer&gt;</span>
</pre>
          </div>
        </div>
        <p><br class="example-break" />
    </p>
      </div>
      <div class="refsect1">
        <a id="idp95571168"></a>
        <h2>See also</h2>
        <p>
      <a class="link" href="pconvolve.html" title="pconvolve"><em class="citetitle">pconvolve</em></a>, <a class="link" href="dconv.html" title="dconv"><em class="citetitle">dconv</em></a>, <a class="link" href="cvanal.html" title="cvanal"><em class="citetitle">cvanal</em></a>.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp95574576"></a>
        <h2>Credits</h2>
        <p>Author: Greg Sullivan</p>
        <p>1996</p>
        <p>New in version 3.28</p>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="convle.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="OpcodesTop.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="copya2ftab.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">convle </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> copya2ftab</td>
        </tr>
      </table>
    </div>
  </body>
</html>
